The Color Scheme file format is designed to be easy to edit with ResEdit. If you want to create and distribute your own Color Schemes, please send me e-mail at <greg@math.harvard.edu> so that I can keep track of who is designing Color Schemes. Please do NOT send me your schemes.
For the latest information about creating Color Schemes, see the Kaleidoscope Scheme Archive (maintained by Eric Reid) on our web site: <http://www.kaleidoscope.net/>. There you will find a comprehensive archive of third party Color Schemes, several detailed guides for Color Scheme designers, and instructions for submitting your own Color Schemes.
Changes for Kaleidoscope 1.7
Menu and Menu Bar Patterns
Kaleidoscope now uses separate cicn/ppat resources for the menu bar and menus. Resource -12288 continues to be used for the menu bar. In addition, cicn/ppat -12272 is now used for menus themselves. The format for cicn -12272 is the same as for the hilited menu cicn -12287. If you want a menu bar pattern, use ppat -12288. If you want a menu pattern, use ppat -12272 and also include a cicn -12272 resource. For backwards compatibility, If Kaleidoscope cannot find cicn -12272, it uses cicn/ppat -12288 for both menus and the menu bar.
Mixed Check Boxes and Radio Buttons
Mac OS 8 supports mixed states for check boxes and radio buttons. These are inbetween states that are partially, but not completely, selected. For example, mixed check boxes are used in Extensions Manager and the Apple Installer (although these are custom jobs not patched by Kaleidoscope). You should add mixed check box and radio button states to your schemes with ics* IDs -10238, -10234, -10230, -10222, -10218, -10214. For backwards compability, if Kaleidoscope cannot find a mixed state, it uses the normal selected state.
Utility Window Grow Boxes
For compatibility with the utility windows (floating windoids) under Mac OS 8, Kaleidoscope now uses a 16x16 cicn instead of a 17x17 cicn for the grow box (cicn IDs -14313, -14317), and you should update your scheme to use the smaller cicn size. If your scheme uses the wrong size grow box, Kaleidoscope will scale it to the correct size.
Finder Headers and Dialog Backgrounds
Mac OS 8 assumes that Finder window headers (cicn IDs -14312, -14311) use the same background color as dialog boxes (part code 0 in dctb -14336 and part code 1 in clut IDs -14336, -14335). For best results under Mac OS 8, you should use the same colors in all of these places. The problem is that some parts of Mac OS 8 draw bevels or dividers (using colors from the clut resources) or erase to the dialog box background color on top of the window headers. This looks bad if the colors do not agree.
The ﾒclutﾓ Resources
The two ﾒclutﾓ resources are used by the Kaleidoscope control panel and are intended for use by developers who want to make their applications Kaleidoscope-savvy. (Developers should also make their applications Appearance-savvy for use under Mac OS 8; Kaleidoscope hooks into the Appearance manager so that any Appearance-savvy application automatically uses Kaleidoscope's colors.) The part codes are as follows:
Part Code 0: Frame color, used for outlining objects
Part Code 1: Fill color, used as the background
Part Code 2: Text color
Part Code 3: Light tinge, used inside frames on the top and left
Part Code 4: Dark tinge, used inside frames on the bottom and right
Part Code 5: Light bevel color, used for dividers and group boxes
Part Code 6: Dark bevel color, used for dividers and group boxes
Please note that you do not need to use hex when entering red, green, and blue color values. You can use decimal numbers if you leave out the ﾒ$ﾓ prefix.
Color Icons
Nearly all of the interface elements are specified by ﾒcicnﾓ color icon resources. When drawing these interface elements, Kaleidoscope takes the appropriate icon and stretches it. For instance, when drawing buttons or Finder window headers, Kaleidoscope draws the four corners first, then it draws the edges by stretching the colors along the edge of the icon, and finally it fills in the inside with the background color at the center of the icon. For those interface elements that contain text, the icon will have a small dot or line somewhere near the center that indicates the text color.
The icons should be self-explanatory, but if you have any questions about how they work or which icons correspond to which interface elements, please feel free to ask me by e-mail. As people ask questions, I intend to expand this portion of the documentation to include the answers.
Buttons / Popup Menus
The icons for the various states (normal, pushed, and disabled) of push buttons should all have the same mask. Otherwise, when a button switches state, some pixels from the previous state may be left behind. The same applies to the popup menu button.
If some of your push buttons have white squares cut out of their corners, see the ﾒDefault Button Ringsﾓ paragraph below. You need to leave a hole in the default button ring icon mask for the push button itself. Otherwise, the corners of the default button ring overwrite the corners of the push button.
Windows
The icons for windows, dialog boxes, and alerts look like miniature windows. Although the icons for window, dialog boxes, and alerts look the same, they are used slightly differently. Normal document windows are drawn by simply stretching the icon, using a six pixel thick border on the left, bottom, and right of the window. The contents of the small square inside the icon are ignored. For alerts and dialog boxes, the contents of that square are used to determine the bevels on the inside border of the dialog, and the border of the icon is used to draw the title bar if the dialog is a movable modal. Alerts and dialog boxes do not have a thick outer border.
Near the top of the various window icons, there is a two pixel horizontal line which Kaleidoscope uses to determine the text color for the window title bar. Starting with version 1.5.1, Kaleidoscope supports embossed window titles (it draws the title shifted one pixel down and to the right in a different color behind the normal title). To set the embossing color, use the pixel immediately to the right of the two text color pixels. If you do not want this embossed effect, leave this pixel the same color as the rest of the window background.
Utility Windows (aka Floating Windows or Windoids)
Utility windows draw the same way as normal windows, except that utility windows can have the title bar on the left side instead of on the top. Icons -14320 and -14316 are used when drawing the inactive and normal states of utility windows with the title bar on the top, and icons -14319 and -14315 are used to draw the side title bar variants. When drawing the racing stripe pattern for utility windows, Kaleidoscope does not stretch the icon; rather, it tiles the icon, repeating it across the length of the title bar. Icon -14314 is used for top title bars, and icon -14318 is used for side title bars.
Menus
The color icon with ID -12288 is used to draw the menu bar. The left and right sides of the icon are used to draw the corners of the menu bar, and the icon mask indicates which pixels are to be plotted. Please note that these corners are used only on screens with rounded menu bars, and Kaleidoscope does not change the shape of the menu bar. The rows of pixels at the top and bottom of the icon are used for the one pixel tinge around the border of the menu bar. In the middle of the icon, the background color is use for the background of the menu bar. The upper horizontal line gives the text color, and the two lower horizontal lines give the colors to be used for the menu dividers. Disabled menu items are drawn using the average of the text and background colors; Kaleidoscope does not let you set the disabled menu item color directly.
The color icons with IDs -12272 and -12287 are used to draw normal and highlighted menu items respectively. The columns of pixels on the left and right side are used for the tinges on the left and right side of the menu. The thick horizontal line in the middle of the icon gives the text color, and the ring around it gives the background color for the menu item. Icon -12287 is also used to draw highlighted menu titles in the menu bar.
Scroll Bar Thumbs
Kaleidoscope determines the height of the scroll bar thumb from the corresponding icons (IDs -10208, -10207, and -8272 for the normal, pressed, and ghost thumb variants respectively). In most color schemes, the scroll bar thumb is 17 pixels high. However, in the ﾒSystem 7ﾓ color scheme, the scroll bar thumb is only 16 pixels high, and it is 20 pixels high in the ﾒBeBoxﾒ color scheme. The scroll bar thumb icons must all be 16 pixels wide, as that is the normal width of scroll bars. (The above discussion is for vertical scrollbars. Forhorizontal scrollbars, the thumbs are determined by icons -10206, -10205 and -8271, and the same holds with ﾒheightﾓ and ﾒwidthﾓ reversed.)
Kaleidoscope provides support for proportional scroll bars with SmartScroll 2.03 or later. To stretch the scroll bar thumb, Kaleidoscope's default behavior is to stretch from both the top and the bottom, three pixels in from the edge. This gives the thumb a solid look with the grip area in the center. Kaleidoscope also provides the option via the ﾒColrﾓ 129 resource (described below) to stretch the thumb from the center. This center stretching is used in the ﾒSherbet IIﾓ color scheme.
Changing Shapes
Push buttons, default button rings, popup menus, and window widgets (close box, zoom box, windowshade box) can take on a variety of shapes. Kaleidoscope uses the mask for the appropriate icons to determine the shape of the object. So, for instance, you can create buttons that are square or window widgets that are round. Please note that you cannot change the shape of the windows or scroll bars.
Default Button Rings
Be sure to leave a hole in the default button ring icon mask for the push button itself. Otherwise, the corners of the default button ring overwrite the corners of the push button, resulting in push buttons that have white squares cut out of their corners.
Using Patterns
The menus, scroll bar track, and window racing stripes now support patterns. Just add a ﾒppatﾓ resource to the color scheme with the same ID as the appropriate ﾒcicnﾓ resource. For menus, Kaleidoscope automatically uses the pattern instead of the background color specified in the icon. For the scroll bar track and window racing stripes, any pixels of the icon that are not contained in the mask are filled with the pattern. This lets you use the icon to create a border around the area filled with the pattern. You can use any size pattern you want, but if your patterns get too large and use too many colors, you may run into memory problems (i.e., the pattern will refuse to draw, leaving a hole. The only way to know if this will happen is to thoroughly test your color scheme).
The ﾒactbﾓ, ﾒdctbﾓ Resources
The ﾒactbﾓ and ﾒdctbﾓ resources are alert and dialog color tables. These are used to specify the background color (part code 0) and text color (part code 2) of alerts and dialog boxes. The other entries of the color table are ignored. Please note that the alert background color must be different from the dialog box background color, as this is how Kaleidoscope distinguishes between alerts and normal dialog boxes. If you want to use the same background color for both, change the alert color by adding or subtracting 1 from each of its red, green, and blue values.
Please note that you do not need to use hex when entering red, green, and blue color values. You can use decimal numbers if you leave out the ﾒ$ﾓ prefix.
Finder Icons
If you put Finder icons (icl* and ics* resources corresponding to folders) in a color scheme file, they override the corresponding icons in the Kaleidoscope file. However, due to the way the Finder caches its icons, the Finder icons do not update immediately when you switch schemes, and the only way to reload the new icons is to restart the Finder. If the user switches between two color schemes that use different Finder icons, Kaleidoscope presents a note alert explaining the situation. Kaleidoscope does not currently support substitute Finder icons under Mac OS 8, but we hope to fix this in time for the Mac OS 8 release.
Version Information
Kaleidoscope stores information about the color scheme file format version and various scheme-specific flags in the ﾒColrﾓ 129 resource. All of the color schemes that come with Kaleidoscope have a template (ﾒTMPLﾓ resource) for editing this resource. The first field is the version of the ﾒColrﾓ resource itself, which is currently 1. The second field is the version number of the color scheme file format. This field will be used by future versions of Kaleidoscope to recognize older, possibly incompatible, color scheme formats, and as of this writing it should be set to 1. The third field is the minimum version of Kaleidoscope that is required to use this color scheme. It is a hex byte whose digits give the Kaleidoscope version number. For instance, to indicate Kaleidoscope 1.5, this field should be set to $15. If a color scheme gives a minimum version number that is higher than the current version number, Kaleidoscope will conclude that the color scheme is too new and will not attempt to use it. The remaining two fields indicate whether the color scheme has accent colors, such as the ﾒApple Grayscaleﾒ color scheme, and whether scroll bar thumbs should be stretched from the center (see ﾒScroll Bar Thumbsﾓ above). The remaining data in the ﾒColrﾓ resource is reserved for future use. The ﾒColrﾓ 128 resource is ignored.
Color Scheme About Box
You can provide about boxes in your color schemes giving contact and copyright information, words of thanks or wisdom, cool graphics, or anything else you want. If the user clicks the Kaleidoscope logo at the top left of the control panel, Kaleidoscope looks for the resource ﾒDLOGﾓ -14320 in the active color scheme file. If Kaleidoscope finds such a resource, it draws the corresponding dialog box, waits for a mouse click, and then erases the dialog. Kaleidoscope sets the default font for this dialog box to Geneva 10 to match the rest of the control panel. You can do whatever you like with this dialog box, as long as you number all associated resources in the range -14320 through -14304 (to avoid conflicting with other applications).
The ﾒSystem Heapﾓ Bit
Please make sure that all of the resources in your color schemes have the ﾒSystem Heapﾓ bit set. You can see the status of the ﾒSysﾓ bit in ResEdit by choosing one of the list views and checking the ﾒShow Attributesﾓ menu item. To change this bit, use the ﾒGet Resource Infoﾓ command. If this bit is not set, it can cause various problems, ranging from garbled icons to crashes.
Converting old (Kaleidoscope 1.0.x) Color Schemes
Please note that the resource IDs for the various icons in the color scheme file have changed since Kaleidoscope 1.0.x. So, you must be sure to renumber your icons instead of just dumping the old icons into the new color scheme file. To make the conversion process easier, we have included a ﾒScheme Updaterﾒ application that translates color schemes from the old 1.0.x format to the new 1.5 format.
Do not edit a Color Scheme that is in use!
Never attempt to edit the color scheme that is currently selected in the Kaleidoscope control panel. Doing so can cause crashes, possibly corrupting the color scheme file. If you want to edit the active color scheme, you must open the Kaleidoscope control panel and select a different color scheme first. Once you have finished editing the color scheme (and you have closed the file in ResEdit or Resorceror), you can switch back to it immediately.
